Skip to content

feat(agents): add roster() + presence() methods (cueapi #630 + #662 parity)#35

Merged
mikemolinet merged 1 commit into
mainfrom
feat/agents-roster-presence
May 9, 2026
Merged

feat(agents): add roster() + presence() methods (cueapi #630 + #662 parity)#35
mikemolinet merged 1 commit into
mainfrom
feat/agents-roster-presence

Conversation

@mikemolinet
Copy link
Copy Markdown
Collaborator

Summary

Adds two SDK methods to AgentsResource covering the Agent Directory v0/v1/v2 surface:

SDK method Endpoint Server PR Purpose
agents.roster(if_none_match=None) GET /v1/agents/roster cueapi #630 List every agent owned by the calling key with presence block
agents.presence(ref) GET /v1/agents/{ref}/presence cueapi #662 Cheap-poll a single agent's presence fields (online, derived_status, bucketed_seen, default_live, labeled_sessions, etag) without the full record

Use cases

  • roster(): directory UIs (Cue Bar, Dock CMA), sender-side recipient choice based on presence
  • presence(ref): UI tiles that refresh every few seconds without re-fetching the directory or full agent record

ETag support on roster

roster() accepts an if_none_match kwarg flowing as the If-None-Match HTTP header. When the server determines the directory hasn't changed since that ETag, it returns 304 Not Modified — the client lib will surface that as a CueAPIError with status 304 (caller catches and reuses the cached payload).

Tests

4 new mock-based tests in test_agents_resource.py:

  1. test_roster_no_etag — no If-None-Match header by default
  2. test_roster_with_if_none_match — header flows correctly with weak-etag prefix
  3. test_presence_by_id — opaque agt_<12 alnum> path
  4. test_presence_by_slug_formslug@user path

Source

Drift audit handoff/cueapi-package-drift-2026-05-06. Backlog rows:

  • "Parity port: PR #630 (GET /v1/agents/roster) → cueapi-python" (p2)
  • "Parity port: PR #662 (GET /v1/agents/{ref}/presence) → cueapi-python" (p2)

Related

Test plan

  • All 4 new tests pass via mock
  • No regression on existing TestList/TestGet/etc.
  • roster() and presence() correctly added to public AgentsResource API

🤖 Generated with Claude Code

…arity)

Adds two SDK methods to ``AgentsResource`` covering the Agent Directory
v0/v1/v2 surface:

  - ``roster(*, if_none_match=None)`` — GET /v1/agents/roster
    Lists every agent owned by the calling key with a presence block
    (online, derived_status, bucketed_seen, default_live cue, labeled
    sessions, etag). Supports ``If-None-Match`` header so cheap-poll
    callers can skip the payload when the directory hasn't changed.

  - ``presence(ref)`` — GET /v1/agents/{ref}/presence
    Lighter than ``get(ref)`` — returns just the presence-relevant
    fields (online, derived_status, bucketed_seen, default_live,
    labeled_sessions, etag) without the full agent record. Designed
    for UIs refreshing a single tile every few seconds without
    re-fetching the directory or full agent record.

4 new mock-based tests in test_agents_resource.py:

  - test_roster_no_etag — no If-None-Match header by default
  - test_roster_with_if_none_match — header flows as ``If-None-Match``
  - test_presence_by_id — opaque agent_id path
  - test_presence_by_slug_form — slug@user path

Source: drift audit handoff/cueapi-package-drift-2026-05-06; Backlog
rows "Parity port: PR #630 (GET /v1/agents/roster) → cueapi-python"
+ "Parity port: PR #662 (GET /v1/agents/{ref}/presence) → cueapi-python"
(both p2, CTO-SEC-DRIFT-AUDIT-AUTHORIZE 2026-05-06).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@govindkavaturi-art govindkavaturi-art enabled auto-merge (squash) May 7, 2026 00:42
@mikemolinet mikemolinet merged commit eb49a3f into main May 9, 2026
4 checks passed
@mikemolinet mikemolinet deleted the feat/agents-roster-presence branch May 9, 2026 21:07
mikemolinet added a commit that referenced this pull request May 9, 2026
…t recent ports (#36)

Manifest was 3 days stale; many endpoints listed as missing have
been ported since the last audit.

Moved from endpoints_missing → endpoints_covered (with PR refs):

  - POST /v1/cues/{id}/fire (PR #23; in-flight kwargs in #33)
  - POST /v1/executions/{id}/replay (PR #25)
  - GET /v1/executions/claimable (PR #23)
  - POST /v1/executions/{id}/claim (PR #23)
  - POST /v1/executions/claim (PR #23)
  - GET /v1/workers + DELETE /v1/workers/{id} (PR #26)
  - GET /v1/usage (PR #26)
  - POST /v1/agents + GET/PATCH/DELETE /v1/agents/{ref}
    + GET /v1/agents/{ref}/webhook-secret
    + GET /v1/agents/{ref}/inbox + /sent (PR #27)
  - POST /v1/messages + GET/read/ack (PR #28)

Added in-flight refs (open PRs):

  - GET /v1/agents/roster (in-flight PR #35; cueapi #630 parity)
  - GET /v1/agents/{ref}/presence (in-flight PR #35; cueapi #662 parity)
  - send_at + exit_criteria + idempotency_key kwargs on fire (PR #33)
  - send_at kwarg on messages.send (PR #34)

New endpoints_missing items (post-audit):

  - POST /v1/agents/{ref}/webhook-secret/regenerate (destructive; tracked)
  - DELETE /v1/messages bulk (cueapi #650; bounded by cueapi-cli upstream)
  - POST /v1/executions/{id}/live-claim (cueapi #664; handler-runtime, not SDK)

New "in_flight_ports_2026_05_07" section listing all 4 currently-open
SDK PRs with PR-overlap notes (PR #30/#33 lane-flagged with cueapi-main).

Bumped sdk_version_at_audit 0.1.3 → 0.2.x.

This refresh closes the Backlog row "Refresh cueapi-python parity-manifest.json"
filed earlier today (Self-flag 2026-05-07).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mikemolinet added a commit that referenced this pull request May 12, 2026
…dy coverage, bump audit to 2026-05-12 (#43)

Manifest was dated 2026-05-07 and missing the PR-1b event-emit endpoint
coverage (4 endpoints) plus the body-verify Phase 2 + inline_body
extensions that shipped 2026-05-09 → 2026-05-12. Brings the manifest
back in sync with SDK head.

Endpoints added to `endpoints_covered`:
- POST /v1/agents/{ref}/subscriptions (subscriptions_create, PR #38;
  inline_body kwarg in PR #42 / cueapi #791 Item 1)
- GET /v1/agents/{ref}/subscriptions (subscriptions_list, PR #38)
- DELETE /v1/agents/{ref}/subscriptions/{sub_id} (subscriptions_delete,
  PR #38)
- GET /v1/agents/{ref}/events (events_pull, PR #38)

Updates to existing entries:
- POST /v1/messages — added auto_verify body-verify Phase 2 (PR #39 +
  #40, cueapi/cueapi #795 + #798 parity)
- POST /v1/cues/{id}/fire — note that #33 shipped (was "in-flight")
- GET /v1/agents/roster — note that #35 shipped (was "in-flight")
- GET /v1/agents/{ref}/presence — note that #35 shipped (was "in-flight")

Replaced `in_flight_ports_2026_05_07` section with
`ports_shipped_2026_05_08_to_2026_05_12` (now-resolved entries) plus a
near-empty `ports_in_flight_2026_05_12` placeholder for future ports.

Backlog row: cmp1vukmc.

Out of scope:
- `model_drift` section walk-through (Cue/Execution/Worker missing
  fields) — PR #31 just landed the Execution + Worker + Agent +
  Message additive models; a fuller `model_drift` refresh deserves a
  separate audit pass against the now-shipped models to figure out
  what's still drifting.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant